Introduction
At the GeoServer Project we believe that the open source process can be applied to more than just software. As such the documentation of GeoServer is run in a completely open source manner, as everything is a wiki, that anyone can edit. Every user is a potential contributor, and we encourage you to improve the documentation where ever you think it could be better.
This document presents a few guidelines for doing so, especially to edit the core documentation. But even if you're not up to that, there a few easy ways to get involved. The best is the 7 User Experiences section, where you can informally write a few words about what you're doing with GeoServer, put up a link to something you made with GeoServer, or write a more formal tutorial on using GeoServer. You can also comment on any portion of the docs, and the developers can do the job of incorporating it.
And if you have any ideas on how to improve the docs, we'd love to hear them. Though we just might ask you to be the one to take the lead 
Signing up for an account
In order to do anything beyond commenting, you'll need an account on our confluence wiki system. This is mostly for a bit of accountability, so we know who was the one to put a comment up. The main reason is to prevent wiki spam, and just because we like to know the people who are helping out. It puts your name on the pages you edit, and gives you a small bit of credit for your contribution. If we see your name enough times we'll add it to the contributors list. If you want to be anonymous, you can still contribute, it just has to be in the comments. Every page should have a 'Add a Comment' link at the bottom.
To create a confluence account, you just need to click on the 'Sign Up' in the upper right corner of (the online version of) this page. You must enter your name, your email address, a user name, and a password. The email address is only used to send you notifications about things related to the wiki space. You can sign up to be notified when certain pages are updated, for example. Your email address will never be used for any type of spam.
Recently our codehaus host has unfortunately locked down wiki editing a bunch. So now there are several additional annoying steps. We are working on a better solution, but until then after making a username on confluence there are a couple additional steps:
- Create an account for codehaus: http://xircles.codehaus.org/signup^
- Go to your personal details page: http://xircles.codehaus.org/my/details^
Use the form to fill in your Confluence Username from step one - Go to the GeoServer project page http://xircles.codehaus.org/projects/geoserver
And click on Apply to join as a developer - Notify the devel list, and permission will soon be granted.
How to edit a page.
To edit a page, if you have proper permissions you can hit 'Page Operations' on the left side bar, and that should pop-up some options, including 'Edit'. If you select this button you will see the editor. There are two ways to edit, with the Rich Text visual editor, which works like a simplified word processor. It is good for basic edits, but for more advanced formatting we recommend the straight Wiki Markup editor (you can toggle between the two as well as the Preview page with tabs at the top). The syntax for this editor should appear on the right in a Help Tips columns. And there is also a link to the full notation guide, which is very helpful to figure out the advanced features of confluence. There are a number of very nice macros that one can use, and we recommend making use of them, to make the docs look good. There are many examples on the pages themselves as well.
Editing Recommendations
Voice
We'd like to keep a relatively consistent voice to the documentation, or at least as consistent as you can get with an incredibly diverse group of contributors. This does not mean that you should not contribute if you feel your English is a bit weak for example, just that you should then point someone else at what you wrote to clean it up. It's much easier to clean up already written documentation than it is to write something new, and indeed just starting will often get others excited to contribute more. But before editing it can be helpful to read a bit of the other docs, just to get a sense of how the docs come off. Obviously we are fine with the use of 'you', these aren't extreme technical specs, but more guides on how to get going with GeoServer, along with useful advice. The biggest effort should be to make things straightforward, clear steps explaining the topic.
Formatting
Good formatting is actually very important. A few visual breaks actually make things a lot easier to read. Try to write no more than a few paragraphs without some sort of heading. There are a few nice notations that can easily generate some nice formatting. Lists are easily achieved with a series of *, -, or #, or nested combinations thereof. Tables can be created with ||head1||head2||, and columns are easily defined with a column macro. One of our favorites is the code macro, which performs syntax highlights on java code and xml. See the notation guide for more details.
Links
Feel free to use all sorts of wiki links within the GEOSDOC (documentation) space, and link externally as well, and don't hesitate to use shortcut names on the hyperlinks. The one thing that we ask that you avoid the [GEOS:Latest] format. To most of you this won't mean much - basically you can easily link to a page in another 'space' (like GeoTools), with a shortcut of its prefix. This is nice, as it will correct your links if the page changes names, but we recommend against it due to the exporting we do with our docs. The wiki docs are turned into html and included with each release, and using the shortcut links will break them on export. Instead you should include the full url to locations in other spaces.
(todo: check to see if they perhaps fixed this with Confluence 2.0, as codehaus was upgraded, and it may be that export works better now)
Page Location
One of the organization techniques of the documentation is the Documentation Tree, which presents a hierarchical view of all the pages. It is important that new pages slot in correctly to this tree, instead of just being located in random places.
The easiest way to do this is to just create the new page from the page to which is most closely related. That will automatically make the page it was created on the 'parent' page, and thus place it correctly in the hierarchy. If the new page shouldn't be a child of the page it was created on, then it should be slotted correctly into the hierarchy. To do this just identify the title of the page that should be its parent, and edit the 'location' field right below the title. This will pop up a text box with the parent, which can be changed to the title of the new parent page.
The location to put the page in should be fairly obvious from looking at the current hierarchy, just find pages that are similar. The one slightly tricky one is 'tutorials', as they are not in the top level Tutorial section, but instead in sub-sections. So create the tutorial in the section of the docs it should go in, and then link from the top-level Tutorial page.
Tutorials
Tutorials are an essential part of the documentation, but they are a bit different than the normal docs. They are always step by step guides to doing a certain task in GeoServer, and are often cut across several areas of the documentation. They should guide a user or developer through a single set of concrete tasks, with a clear end goal. They are the first entry point for many new users, and thus should have a very high level of clarity, they must be easy to understand. The normal documentation can be viewed as more of a reference, for anyone digging into the depth of GeoServer, it should have all possible information. Tutorials should have exactly enough information to get _anyone_ started.
Here is a tutorial on writing tutorials. If you include a link to a tutorial in your page, make the link green and bold.
Hints and Tricks
Herein we describe some of the useful tips that we've found work well. Best practices 'patterns', if you will, that should make this documentation more coherent.
Brent, wanna talk about the color stuff for tutorials and info and whatnot? I must admit I don't use it when I doc thusfar, but I do like seeing it
Renaming Pages
Don't hesitate to rename a page, but please just use the edit tab and change the title there. This will ensure that all the links to the page will be updated appropriately. It also makes it so version history is maintained, if one just copys and pastes to a new page then we can't see what the page looked like before the move.
Includes
Oftentimes there will be a chunk of information that could live in several places. The Confluence wiki system we use has a nice facility to deal with this, called an 'include'. You can use the macro to use the piece of information somewhere else. Though one can embed any page in any other, we recommend a pattern of using the suffix 'include' on the page, and making the most relevant page where its embedded the parent.
FAQ
Our FAQ is built up by questions that are actually frequently asked on the list. If you have a question that is not addressed by the FAQ, but that you want to see the answer to, the route to follow is first emailing the list. Putting a question in the FAQ with no ready answer is not the way to find out the answer, as our developers don't check the FAQ all that often. If you are asked by a developer to add a question to the FAQ then figure out which section is most appropriate and follow the directions given there.
Attachments
It is often quite useful to attach images and other files to a page. We recommend attaching images directly to the page, but for any other type of file the best thing to do is add it as an attachment to http://docs.codehaus.org/display/GEOS/Attachments and to reference it from the GEOSDOC space. We do this to keep the download size of the documentation down to what is essential. Any pdf file, powerpoint slide, or shapefile can be downloaded by the user on their own.
